package Stdlog::Config;

use 5.008;
use strict;
use warnings;
use Scalar::Util qw(reftype);


sub config {
    my ($pkg, $conf) = @_;
    
    if( reftype($conf) eq 'HASH' ) {
        $conf = $conf->{stdlog} if exists $conf->{stdlog};
        $conf = $conf->{logger} if exists $conf->{logger};
    }
    my $loggers = Stdlog->loggers();
    if (reftype($conf) eq 'ARRAY') {   
        @$loggers = (Stdlog->default_logger());
        for (reverse @$conf) {
            unshift @$loggers, Stdlog::Logger->new($_);
        }
    } elsif (reftype($conf) eq 'HASH') {
        @$loggers = (Stdlog::Logger->new($conf));
    } else {
        die "Invalid Stdlog configuration\n";
    }
}



1;
__END__

=head1 NAME

Stdlog::Config - the many ways to configure Stdlog

=head1 SYNOPSIS

The canonical format for Stdlog configuration is an arrayref:

  $conf = [
      {
          name     => 'basic',
          continue => 0,
          
          # logging criteria
          facility => 'foo.pl',
          package  => 'main, /^Foo::/'

          # output format string
          format   => '${date} ${severity} ${message}',
          
          # target writer
          writer   => 'File',
          filename => '/var/log/${facility}/${date}.log'
      },
      {
          name     => 'default',
          format   => '${message}',
          writer   => 'STDERR'
      }
  ];

or it can be a hashref where the keys are the names of the loggers:

  $conf = {
      'basic' => {
          ...
      },
      'default' => {
          ...
      }
  }


Using Config::General *.conf files:

  <stdlog>
    <logger>
      facility    foo.pl
      format      ${date} ${severity} ${message}
      filename    /var/log/${facility}/${date}.log
      continue    0
    </logger>
  </stdlog>
  
Finally, in your program:

  use Stdlog;
  
  Stdlog->config($conf)

=head1 DESCRIPTION

Stdlog::Config provides an API for configuring Stdlog at runtime.

=head1 PUBLIC STATIC METHODS

=head2 Stdlog::Config->get_logger($id|$idx)

=head2 Stdlog::Config->get_logger($id|$idx)


=head1 CONFIGURATIOn

=head2 Formatting Directives

=over 8

=item - format

The format string to use when logging.  See, Stdlog::Formatter for more
information on how to specify formatting strings.

=item - fields

(unimplemented)


=back


=head2 Targetting Directives

=over 8

=item target

Specifies the class of target to use.  Currently, only "File" and "STDERR" is
supported.  Soon, dbi, socket and syslog The default is "file.

=item filename

Log to a file with the specified filename.  This makes Stdlog assume that the
target is "File".  See Stdlog::Writer::File for more information on how to
specify filenames.

The default value is: /var/log/${facility}/${date}.log

=item socket

(unimplemented)

=item dsn

=item username

=item password

=item dbopts

=item table

(unimplemented)

=back


=head2 Criteria Directives

=over 8

=item - facility

This checks against $0, the program name.  If the global flag, $prune_facility
is set to true, then Loggers are created based on the facility criteria when
Stdlog is configured.  Thus, if you want to change $0, do so before calling
Stdlog->config.

Examples:

   your-program
   /something/

=item - severity

This checks against the severity of the logging function used.  Severity must
be one of the following: DEBUG, INFO, NOTICE, ERROR, or FATAL.  They can be
combined by using the modifier + or -, as in NOTICE+, which means "NOTICE or
higher" (i.e. NOTICE, ERROR, and FATAL).  They can also be listed explicitly
using a space or comma seperated list.

Examples:

    NOTICE+
    DEBUG, INFO

=item - package

This checks against package name.  Multiple package names can be specified
by seperating them with commas.  Note, the default package is "main".

Examples:

    Foo::Bar
    /^Foo::Bar::/
    Alpha, Bravo::Charlie, Delta::Eagle::Foxtrot

=item -expression

If the supplied expression evaluates to true, log it.

Examples:

    $opts->{foo} eq 'bar'
    $ENV{REMOTE_HOST} == '12.34.56.78'
    $main::VERBOSE
    
=back


=head2 Other Directives

=over 8

=item continue

If true, will check the next logger, which means the same data could be logged
to multiple targets.  The default is true.

=back


=head1 EXAMPLES

=head2 Config::General


=head2 Config::INI


=head2 XML::Simple



=head1 SEE ALSO


=head1 AUTHOR

Robert Mah E<lt>rmah@pobox.comE<gt>


=head1 COPYRIGHT AND LICENSE

Copyright (C) 2009 by Robert Mah

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.

=cut
